home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 July / EnigmA AMIGA RUN 09 (1996)(G.R. Edizioni)(IT)[!][issue 1996-07 & 08][EARSAN CD VIII].iso / earcd / util3 / wat.lha / WAT.Doc < prev    next >
Text File  |  1996-06-03  |  7KB  |  168 lines
  1.                                  WAT
  2.                                  ---
  3.  
  4.                         Version 1.00 - June 1996
  5.  
  6.                      Copyright © Michael Tanzer 1996
  7.  
  8. +---------------------------------------------------------------------------+
  9. |                             N O T I C E                                   |
  10. |                                                                           |
  11. | Freely distributable.  Not to be used for commercial purposes without     |
  12. | written consent from the author.  Not to be distributed without this      |
  13. | notice and accompanying components intact.                                |
  14. |                                                                           |
  15. | This product is distributed on an 'as-is' basis, with no warranty of any  |
  16. | kind, either express or implied.  No responsibility whatsoever is assumed |
  17. | by the author for the use of this product, nor for any results of its     |
  18. | use.  No claim whatsoever is made as to this product's accuracy, useful-  |
  19. | ness, completeness, nor suitability to any purpose.                       |
  20. |                                                                           |
  21. | Components include the following files:                                   |
  22. |   WAT                                                                     |
  23. |   WAT.info                                                                |
  24. |   WAT.Doc (this document)                                                 |
  25. |   WAT.Doc.info                                                            |
  26. |                                                                           |
  27. +---------------------------------------------------------------------------+
  28.  
  29.  
  30. What's WAT?
  31. -----------
  32.  
  33. WAT ('What?! Another Timer?!') is a timer utility written in Rexx.
  34.  
  35.  
  36. Why WAT?
  37. --------
  38.  
  39. WAT is a simple timer that displays the time it was started, the time it
  40. was stopped, and the elapsed time in between.  It has virtually no CPU
  41. overheads while it is active because the only time it does anything is
  42. when you stop it or restart it.
  43.  
  44. You can run multiple copies of WAT, and optionally specify a port name
  45. so that other ARexx programs can tell WAT when to start, stop, or quit.
  46.  
  47. WAT runs asynchronously, so you can run it without tying up a shell.
  48.  
  49. Best of all, WAT is written in Rexx, so if you want to add or change a
  50. feature, you can do it easily.  And it's free.
  51.  
  52.  
  53. What you need in order to use WAT:
  54. ----------------------------------
  55.  
  56. You must have the following libraries in your LIBS: directory:
  57.   rexxsyslib.library    (version 36.17 or later)
  58.   rexxsupport.library   (version 34.9  or later)
  59.   rexxarplib.library    (version  3.0  or later)
  60.   arp.library           (version 39.1  or later)
  61.   screenshare.library   (version  1.46 or later - required only for WB1.3)
  62.  
  63. The RX and WaitForPort commands should be contained in a directory that is
  64. in your default path.  In WB2+ they are in the Rexxc directory.
  65.  
  66.  
  67. How to implement WAT:
  68. ---------------------
  69.  
  70. Copy WAT to your REXX: directory.  If you are running WB2 or later, make
  71. sure the 'script' flag is set.
  72.  
  73. If you want to start WAT with an icon, copy WAT.info to the drawer of your
  74. choice.
  75.  
  76. If you use a large font for screen text, you may find that the window title
  77. overlays part of the window contents.  In this case, try adding 1 or 2 to
  78. the value of the 'blanks' variable at the beginning of the program.
  79.  
  80.  
  81. How to use WAT:
  82. ---------------
  83.  
  84. To run WAT from the Workbench, double-click the WAT icon.
  85.  
  86. To run WAT from a WB2+ shell, enter:
  87.     WAT <portname>
  88.  
  89. From a WB1.3 shell, enter:
  90.     RX WAT <portname>
  91.  
  92. The WAT window displays the time at which WAT was started (or re-started),
  93. the time at which it was stopped, and the elapsed time in between.  Clicking
  94. on the 'START' gadget will re-start the timer and clear the elapsed time.
  95. Clicking on the 'STOP' gadget will cause the 'stopped' time to be updated
  96. and the elapsed time to be calculated.  The timer never actually stops, so
  97. you can click on the 'STOP' gadget repeatedly, getting an updated display
  98. each time.  In order to minimise CPU utilisation, the elapsed time is not
  99. updated automatically.  If you're into watching numbers change, get a clock.
  100.  
  101. If you specify a port name, it will be displayed on WAT's window and menu.
  102. If no port name is specified, 'WAT' will be used first, then 'WAT1', WAT2',
  103. etc. depending on how many copies of WAT are already active.  Note that
  104. any port name specified will be converted to upper case before use.
  105.  
  106. The default position for the WAT window is in the upper left hand corner
  107. of the screen, but you can change this by dragging the window to the your
  108. preferred location and selecting 'Save prefs' from the menu.  The screen
  109. position will be stored in a configuration file ('S:WAT.config').
  110.  
  111. You can control WAT from another ARexx program by using the ADDRESS instruc-
  112. tion to indicate the desired WAT notify port, then specifying one of the
  113. following commands:
  114.  
  115.   Command       Action
  116.   -------       ------
  117.   QUIT          Terminates the WAT display
  118.   CLOSEWINDOW   Terminates the WAT display
  119.   START         Re-starts the timer
  120.   STOP          Stops the timer
  121.   SPREF         Stores the window position in the config file
  122.  
  123. For example, if you wanted to use WAT to display the time it took to run a
  124. particular Rexx program, you could put the following lines at the beginning
  125. of the program:
  126.   if wat(quack) then address command 'WAITFORPORT QUACK'
  127.   else do /* followed by logic to handle WAT failure */
  128. Then at the end of the program, insert the following:
  129.   address quack 'STOP'
  130. to cause the WAT window displaying the name 'QUACK' to show the time
  131. elapsed during the running of the program.  Of course, if your program was
  132. written in Rexx, you'll probably use the time('r') and time('e') functions
  133. instead of WAT, but the facility is there if you need it.  Note that, if
  134. called as a function, WAT will return a '1' or a '0' to indicate successful
  135. or unsuccessful initialisation, respectively.
  136.  
  137.  
  138. Version log:
  139. ------------
  140.  
  141. 1.00  JUN 1996  Original release.
  142.  
  143.  
  144. Other things you might like to know about WAT:
  145. ----------------------------------------------
  146.  
  147. Before you make any complicated changes, comment out the paragraph at the
  148. top of the program having the comment 'Run WAT asynchronously' so that you
  149. can insert trace commands, etc. as required (but leave in the call to
  150. 'getnport'), then invoke the test version from a shell.  It may also be
  151. advisable to comment out the 'signal on halt' and 'trace b' lines that
  152. appear at the top of the main control loop.
  153.  
  154. You are free use WAT for as long as you like and to modify it in any way
  155. that suits your needs, but please do not distribute a modified version.  I
  156. do not ask for any remuneration, but if you would like to send me anything
  157. I would be delighted to receive it (all right, even another Porsche).  I
  158. will make a sincere effort to answer any questions you may have about WAT.
  159. My address is:
  160.  
  161.     Michael Tanzer
  162.     P.O. Box 289
  163.     Carlton North VIC 3054
  164.     Australia
  165.  
  166.     Telephone:  +61 3 9387 6589
  167.     Facsimile:  +61 3 9388 1863
  168.